home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / f90 / ffpos.z / ffpos
Encoding:
Text File  |  1998-10-30  |  13.7 KB  |  250 lines
  1. FFPOS(3C)                                             Last changed: 2-17-98
  2.  
  3.  
  4. NNAAMMEE
  5.      ffffppooss - Positions files opened using flexible file I/O
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<ffffiioo..hh>>
  9.  
  10.      UNICOS and UNICOS/mk systems:
  11.  
  12.         iinntt ffffppooss ((iinntt _f_d, iinntt _c_m_d, lloonngg **_a_r_g , iinntt _l_e_n, ssttrruucctt ffffssww
  13.         **_s_t_a_t));;
  14.  
  15.      IRIX systems:
  16.  
  17.         ooffff__tt ffffppooss ((iinntt _f_d, iinntt _c_m_d, vvooiidd **_a_r_g , iinntt _l_e_n, ssttrruucctt ffffssww
  18.         **_s_t_a_t));;
  19.  
  20. IIMMPPLLEEMMEENNTTAATTIIOONN
  21.      UNICOS, UNICOS/mk, and IRIX systems
  22.  
  23. DDEESSCCRRIIPPTTIIOONN
  24.      The ffffppooss function provides a way of positioning files opened by
  25.      ffffooppeenn or ffffooppeennss (see ffffooppeenn(3C)), using flexible file I/O (FFIO).
  26.      The arguments are as follows:
  27.  
  28.      _f_d     Value returned by ffffooppeenn or ffffooppeennss.
  29.  
  30.      _c_m_d    Specifies a value defined in header file ffffiioo..hh.  See the
  31.             following subsection, VALUES FOR _c_m_d ARGUMENT.
  32.  
  33.      _a_r_g    The type and value of this argument is _c_m_d specific.  See
  34.             preceding descriptions.
  35.  
  36.      _l_e_n    If _c_m_d = FFPP__GGEETTPPOOSS or FFPP__SSEETTPPOOSS, _l_e_n specifies the number of
  37.             Cray words in _a_r_g.  This parameter is ignored for other values
  38.             of _c_m_d.
  39.  
  40.      _s_t_a_t   Pointer to the status return structure.
  41.  
  42.    VVaalluueess ffoorr _c_m_d AArrgguummeenntt
  43.      The following values can be used for the _c_m_d argument introduced
  44.      above.
  45.  
  46.      FFPP__BBSSEEEEKK
  47.           Sets the current file position as specified by **_a_r_g and **((_a_r_g++11)).
  48.           Not supported on IRIX systems.  **_a_r_g contains the bit position
  49.           requested; this must be a byte boundary.  **((_a_r_g++11)) specifies one
  50.           of the following values, defined in header file ssttddiioo..hh:
  51.  
  52.          00 or SSEEEEKK__SSEETT
  53.              Sets the pointer to the value of **_a_r_g, which must be a
  54.              non-negative integer.
  55.  
  56.          11 or SSEEEEKK__CCUURR
  57.              Sets the pointer to the current position, plus or minus **_a_r_g.
  58.              This is supported only in the following layers that are not
  59.              record-oriented; these layers are specified to aassssiiggnn --FF as
  60.              follows: ssyyssccaallll, ssddss, mmrr (memory resident), ccaacchhee, ccaacchheeaa,
  61.              bbuuffaa, eerr9900.
  62.  
  63.          22 or SSEEEEKK__EENNDD
  64.              Sets the pointer to the end of the file, minus **_a_r_g.  **_a_r_g
  65.              must be a non-negative integer.  Not all layers support this
  66.              option.
  67.  
  68.      FFPP__GGAABBSS
  69.          Returns information about the current position in arg, which can
  70.          later be used by a call to ffffppooss with _c_m_d == FFPP__SSAABBSS.  _a_r_g is a
  71.          pointer to structure ffpp__aabbss (defined in header file ffffiioo..hh).
  72.  
  73.          This call is useful only for online tape and ER90 files.  It may
  74.          be used with the ttaappee, eerr9900, or bbuuffaa layers on UNICOS systems.  It
  75.          may be used with the ttaappee layer on CRAY T3E systems.  ER90 files
  76.          are not supported on CRAY T3E systems.  For some devices, some of
  77.          the fields in ffpp__aabbss may be unused.  When this request is made
  78.          after a write function, the library and tape driver flush all
  79.          remaining data from the write behind to the tape before attempting
  80.          to get the position.  When this request is made after a read
  81.          request, an approximate address is returned, since there may be
  82.          data buffered in the controller, system buffers, or library
  83.          buffers.  FFPP__GGAABBSS does not return information about the volume
  84.          serial number (VSN) currently in use.
  85.  
  86.      FFPP__GGEETTPPOOSS
  87.          Returns information about the current position in _a_r_g, which can
  88.          later be used by a call to ffffppooss with _c_m_d _0=FFPP__SSEETTPPOOSS.  For online
  89.          tape files, 2 Cray words are returned in _a_r_g.  For files assigned
  90.          with aassssiiggnn --FF eerr9900, 4 Cray words are returned in _a_r_g.  For files
  91.          assigned with --FF ccooss,,eerr9900, 6 Cray words are returned in _a_r_g.  For
  92.          all other file types, 1 Cray word is returned in _a_r_g.  For ER90
  93.          files, the information returned does not include the VSN.  When
  94.          using the information returned in a call to ffffppooss with
  95.          _c_m_d==FFPP__SSEETTPPOOSS, you must ensure that you are positioned on the
  96.          correct volume.  This command is unsupported for ER90 files that
  97.          use the FFIO tape layer.  Available on UNICOS and UNICOS/mk
  98.          systems.  ER90 files and the eerr9900 layer are not supported on
  99.          CRAY T3E systems.
  100.  
  101.      FFPP__SSAABBSS
  102.          Sets the position as specified in _a_r_g. The information in _a_r_g
  103.          should have been obtained by a previous call to ffffppooss with
  104.          _c_m_d == FFPP__GGAABBSS.  _a_r_g is a pointer to structure ffpp__aabbss.  This call
  105.          is useful only for online tape and ER90 files.  FFPP__SSAABBSS assumes
  106.          that you are currently positioned on the correct VSN.  You must
  107.          have permission to set the position to the specified address when
  108.          using absolute track address positioning.  Tape manager permission
  109.          is required for IBM-compatible tapes.  For ER90 files, tape
  110.          manager permission is required to position outside the current
  111.          partition.  Bypass-label permission or tape manager permission is
  112.          required to position outside the current file, or past a user tape
  113.          mark.  Available on UNICOS and UNICOS/mk systems.  ER90 files and
  114.          the eerr9900 layer are not supported on CRAY T3E systems.
  115.  
  116.      FFPP__SSEETTPPOOSS
  117.          Sets the position as specified by the information in _a_r_g.  The
  118.          information in _a_r_g should have been obtained by a previous call to
  119.          ffffppooss with _c_m_d == FFPP__GGEETTPPOOSS.
  120.  
  121.          Not available on IRIX systems.
  122.  
  123.      FFPP__SSKKIIPPFF
  124.          This value is valid only for online tape files on UNICOS systems
  125.          and on CRAY T3E systems and for ER90 files on UNICOS systems.  It
  126.          directs the system to skip a specified number of files from the
  127.          current position.  The file will not be positioned beyond BOD or
  128.          EOD.  This is used for positioning by user tapemark (see the --TT
  129.          option on the ttppmmnntt(1) command).  It may not be used to position
  130.          to different files within a multifile volume (see the --qq option of
  131.          the ttppmmnntt(1) command.  _a_r_g is a pointer to structure ffffpp__sskkiippff__ss
  132.          (also defined in header file ffffiioo..hh).  This _c_m_d is valid with the
  133.          following FFIO layers: tape.  The fields of this structure have
  134.          the following meaning:
  135.  
  136.          ffffpp__nnffiill    On input, specifies the number of files to skip.  If
  137.                      the value is negative, the file is positioned
  138.                      backward.  On output, contains the number of files
  139.                      skipped.
  140.  
  141.          ffffpp__nnrreecc    Currently unused.
  142.  
  143.      FFPP__SSKKIIPPTTPPMMKK
  144.          This value is valid only for online tape files on UNICOS systems
  145.          and on CRAY T3E systems.  It directs the system to skip a
  146.          specified number of tape marks from the current position. The file
  147.          will not be positioned beyond BOD or EOD. This is used for
  148.          positioning by user tapemark (see the --TT option on the ttppmmnntt(1)
  149.          command).  arg is a pointer to structure ffffpp__sskkiippttppmmkk__ss (defined
  150.          in <<ffffiioo..hh>>). The fields in this structure have the following
  151.          meaning:
  152.  
  153.          ffffpp__nnttppmmkk   On input, specifies the number of tape marks to skip.
  154.                      If the value is negative, the file is positioned
  155.                      backwards. On output, this field contains the number
  156.                      of tape marks left to position.
  157.  
  158.          uunnuusseedd11     This field is reserved.
  159.  
  160.          The FFPP__SSKKIIPPTTPPMMKK _c_m_d functions differently from FFPP__SSKKIIPPFF.  Except
  161.          in the case where you request positioning past EOD, FFPP__SSKKIIPPFF will
  162.          position you at the beginning of a file; that is, FFPP__SSKKIIPPFF will
  163.          position you either at BOD, immediately after a user tape mark, or
  164.          at EOD.  FFPP__SSKKIIPPTTPPMMKK functions like the ioctl TTRR__PPTTMMSS described in
  165.          the _T_a_p_e _S_u_b_s_y_s_t_e_m _U_s_e_r'_s _G_u_i_d_e, publication SG-2051.  It skips
  166.          the specified number of tape marks. If skipping forward, it will
  167.          position you directly after a user tape mark or at EOD. If
  168.          skipping backwards, it will position you directly before a user
  169.          tape mark or at BOD.  This _c_m_d is valid with the following FFIO
  170.          layers:  ttaappee.
  171.  
  172.      FFPP__SSEETTTTPP
  173.          _a_r_g is a pointer to structure ffffpp__sseettttpp__ss (also defined in header
  174.          file ffffiioo..hh).  This _c_m_d is valid with the following FFIO layers:
  175.          ttaappee.
  176.  
  177.          The eerr9900 layer is not supported on CRAY T3E systems.
  178.  
  179.          On input, the fields of ffffpp__sseettttpp__ss have the following meaning:
  180.  
  181.          ffffpp__nnbb
  182.              Number of blocks to position; should always be a positive
  183.              number.
  184.  
  185.          ffffpp__nnbbss__pp
  186.              Indicates the direction of block positioning.  The following
  187.              values are defined in header <ffffiioo..hh>:
  188.  
  189.              FFPP__TTPPOOSS__BBAACCKK
  190.                  Indicates that the ffffpp__nnbb field is the number of blocks to
  191.                  skip backward, relative to the current position.
  192.  
  193.              FFPP__TTPPOOSS__FFOORRWW
  194.                  Indicates that the ffffpp__nnbb field is the number of blocks to
  195.                  skip forward, relative to the current position.
  196.  
  197.              FFPP__TTPPOOSS__AABBSS
  198.                  Indicates that the ffffpp__nnbb field is an absolute block
  199.                  number, relative to the last tape mark number or beginning
  200.                  of the volume.  If a nonzero value is specified for the
  201.                  ffffpp__nnvv field, positioning is absolute with respect to that
  202.                  tape volume.  If ffffpp__nnvv is 0, and the --TT option was not
  203.                  present on the ttppmmnntt(1) command, the position is absolute
  204.                  with respect to the current tape volume.  If ffffpp__nnvv is 0,
  205.                  and the --TT option was present on the ttppmmnntt command, then
  206.                  positioning is absolute with respect to the last tape mark
  207.                  read or written.
  208.  
  209.          ffffpp__nnvv
  210.              Number of volumes to position; should always be a positive
  211.              number.  A volume number of 0 indicates no volume positioning
  212.              is to be performed.
  213.  
  214.          ffffpp__nnvvss__pp
  215.              Indicates the direction of volume positioning.  The following
  216.              values are defined in header file ffffiioo..hh:
  217.  
  218.              FFPP__TTPPOOSS__FFOORRWW   The number of volumes to skip forward, relative
  219.                             to the current position.
  220.  
  221.              FFPP__TTPPOOSS__BBAACCKK   The number of volumes to skip backward,
  222.                             relative to the current position.
  223.  
  224.              FFPP__TTPPOOSS__AABBSS    Specifies an absolute volume number, relative
  225.                             to the beginning of the volume identifier list
  226.                             (specified on the ttppmmnntt(1) command.)
  227.  
  228.          ffffpp__vvii
  229.              Name of volume identifier to be mounted.  A nonzero ffffpp__vvii
  230.              field is invalid if ffffpp__nnbbss__pp is FFPP__TTPPOOSS__FFOORRWW or FFPP__TTPPOOSS__BBAACCKK
  231.              or if ffffpp__nnvvss is FFPP__TTPPOOSS__FFOORRWW or FFPP__TTPPOOSS__BBAACCKK and ffffpp__nnvv is
  232.              nonzero.
  233.  
  234. RREETTUURRNN VVAALLUUEESS
  235.      If _c_m_d is FFPP__BBSSEEEEKK, ffffppooss returns the new bit position of the file on
  236.      success.  For other values of _c_m_d, the ffffppooss function returns 0 on
  237.      success.  On failure, it returns -1 and the ssww__eerrrroorr field of the ssttaatt
  238.      structure contains the error number.
  239.  
  240. SSEEEE AALLSSOO
  241.      ffffooppeenn(3C)
  242.  
  243.      ttppmmnntt(1) in the _U_N_I_C_O_S _U_s_e_r _C_o_m_m_a_n_d_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication
  244.      SR-2011
  245.  
  246.      _T_a_p_e _S_u_b_s_y_s_t_e_m _U_s_e_r'_s _G_u_i_d_e, publication SG-2051
  247.  
  248.      _A_p_p_l_i_c_a_t_i_o_n _P_r_o_g_r_a_m_m_e_r'_s _L_i_b_r_a_r_y _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication
  249.      SR-2165, for the printed version of this man page.
  250.